Shared vs. Instance Classloaders

By default, all managed resources will be assigned a "resource classloader" that is shared (it could be the same as the plugin classloader or the classloader of the parent resource; in either case, the classloader is shared). But for the cases when a resource component needs a create a connection to its actual managed resource (e.g. the JBossAS component needs to use the JBossAS client jars to connect to the managed JBossAS isntance, as in the Hibernate-JBossAS example above), that resource's classloader usually must be different than the normal, shared plugin classloader. That's because the resource will usually need to have within its own classloader the client jars necessary to connect to the managed resource (and those client jars are usually very specific to the version of the resource being managed).

The connecting resource (the JBossAS resource or the JMX server resource in the above example) should be in charge of creating the connection, since it knows how to do it (e.g. the Hibernate plugin doesn't know how to connect to a JBossAS 4.0 or JBossAS 4.3 or JMX Server - at least, it shouldn't have to). Having the connection management delegated to the Hibernate resource's parent resource allows for code reuse and frees child-plugin developers from having to know how to connect to the parent resource where the child resources are running.

But this involves one important problem - the child plugin components need the classes from the parent plugin; and not just any classes, but very specific classes that may be dependent on the exact instance of the parent resource (e.g. it matters a great deal if a parent JBossAS instance is of version 3.6, 4.0 or 4.3 because the client jars are different among all of them).

When you have a resource that requires its own "connection classloader" (that is, a classloader that contains classes necessary to connect to a managed resource), you need to specify the attribute classLoader="instance" on the resource type. In addition, you must make sure your resource type's discovery component implements the ClassLoaderFacet in order for it to tell the plugin container where any additional connection classes (e.g. client jars) can be found for the specific version of the specific resource being managed. For example, the JBossAS Server resource type needs its own resource classloader because it needs to place in that classloader the very specific client jars necessary to connect to the version of JBossAS that is being monitored. So it needs to define its classLoader attribute as "instance" and its discovery component's ClassLoaderFacet needs to return information on the location of the managed JBossAS instance's client jars. With the resource classloader instance created appropriately, the JBossAS plugin components can instantiate the correct client classes and successfully connect to the JBossAS instance being managed.

Any child resources running in that JBossAS resource needs to make sure their components "share" that classloader so they too can use the connection in order to manage the children. For example, if Hibernate is running in JBossAS, the Hibernate components will have the appropriate resource classloaders assigned to them so they can be assured to use that connection in order to monitor Hibernate running in the JBossAS instance.

Let's go over a more generic example. Suppose a developer is writing plugin "Z" - and there are already plugins A, B, C and D that may or may not be deployed. Here's Z's descriptor:

<plugin name="Z">

<depends plugin="A" />

<server name="Z1.server" classLoader="instance"> <!-- notice classLoader attribute -->
   <runs-inside>
      <parent-resource-type name="B1.server" plugin="B"/>
      <parent-resource-type name="C1.server" plugin="C"/>
   </runs-inside>
</server>

<server name="Z2.server" sourcePlugin="D" sourceType="D1" classLoader="instance">
</server>

</plugin>

This means that if Z is deployed, then:

• plugin A must be deployed as well (i.e. if A does not exist, Z will not deploy). This is because <depends plugin="A"/> denotes a "required" dependency.

• plugin D may or may not exist; if it doesn't exist, then Z2.server is ignored and that resource type doesn't really exist.

• Plugin B and plugin C may or may not exist. If they don't exist, then Z1.server has no parent types. If only one of B or C does not exist, Z1.server has the parent types that do exist.

• When Z1.server is detected, the component's classloader is a "resource-level classloader" (because classLoader="instance"). This means that this resource's classloader will be its own classloader. If that classLoader attribute was "shared" (or if it was not specified), that would have meant that the component will share a classloader with its parent resource (which could be the main plugin classloader if this resource does not depend on another resource via injection or extension as defined in the plugin descriptor). In other words, classLoader="shared" would have meant that every resource of type Z1.server would use the same classloader, that of its parent (or the plugin itself).

• With classLoader="instance", the ResourceDiscoveryComponent implementation can optionally define a "ClassLoaderFacet" whose method "getAdditionalClasspathUrls" returns a List<URL> that points to additional jars that should be placed in the resource's classloader. When the plugin container needs to create a classloader for a resource, it checks if the resource's discovery component implements this facet and, if so, it gets the additional classpath URLs and adds them to the resource classloader when it creates it.

  For the Future?

  Would it make sense to allow for a ClassLoaderFacet to provide "hideClasses()" that returns a regex that allows the plugin to tell the PC that its classloader should hide classes (i.e. classes that the plugin wants to provide itself and not have the parent provide) - this is useful if, for example, the plugin wants to use its own JMX classes and not rely on the JMX classes that the parent classloader provides. Nothing like this exists today and, as of today, no use-cases have appeared to indicate this is needed.

• Note that the plugin container does not support "multiple inheritance" of plugins. Having multiple <depends> does not automatically place all classes in all plugins in the resource classloader. Only the one <depends> that has a useClasses attribute set to "true" will mark which plugin has its classes in the resource classloader.

• At the top of the classloader hierarchy above all plugin classloaders and resource classloaders is a "root plugin classloader". This root plugin classloader will hide the RHQ Agent's classes from the plugins themselves. This means that a plugin will not be able to access any classes in any agent libraries, with some exceptions where those exceptions are configurable (e.g. the agent is able to tell the plugin container to pass through log4j.jar so the plugins can use log4j for logging without having to include their own logging jar). This root plugin classloader is configurable such that it can pass through all classes (which is used by the Embedded Jopr project - it needs to allow all plugins to access the embedding JBossAS server classes).

• A discovery component needs to be created in a proper classloader. Top level discovery components (that is, discover components that look for resources which parent will be the top level platform) are created in the plugin classloader itself. Discovery components for child services (i.e. the result of service scans whose discovered resources will have parent resources of servers, specifically NOT the top platform) will be created in a "discovery classloader" that consists of the discovery component's plugin classloader whose parent classloader is that of the parent resource's classloader.

• If a resource is involved in Injection (runs-inside) or Extension (sourcePlugin/sourceType), its classloader depends on its "classLoader" attribute value and its parent's "classLoader" attribute. This table describes the classloader for a resource based on the different combinations:

Note that if a child resource and its parent resource are both from the same plugin, the child will always use the parent's classloader no matter what.

<depends>

There is a <depends> element directly under the <plugin> element that defines one or more parent plugins that the plugin depends on. When using <depends>, you are specifying a "required dependency". This means the plugin will not deploy successfully, unless all <depends> plugins are also successfully deployed. You can define if you want to pull in classes from one of the dependency jars by specifying the "useClasses" attribute of the <depends> tag. <depends useClasses="true" plugin="A"> means the plugin wants to use classes from plugin A. You can only set useClasses to true for one and only one <depends> in a single plugin descriptor. If no <depends> element has a "useClasses" attribute, the last <depends> specified in the plugin descriptor will default its useClasses attribute to true.

If you are only depending on another plugin for its resource types to inject or embed, you usually do not have to specify <depends> on that other plugin. You normally will specify <depends> for one of two reasons:

1. Your plugin needs access to another plugin's classes

2. You want to require that your plugin is only ever deployed when another plugin is also deployed.

Embedded

A <server> or <service> can be a copy of a source resource type found in another plugin - the plugin descriptor specifies this kind of extension through the <server>/<service> elements usage of the "sourcePlugin" and "sourceType" attributes. When sourcePlugin/SourceType is specified, the <server>/<service> will be a copy of the source resource type which means it will have the same metadata as the source with the exception that the <server>/<service> can override the discovery and resource classes and will potentially have a different name. To be clear, the new type cannot add or remove other metadata from the source. This means you cannot add or remove metrics, configuration properties, operations, etc. The new type is essentially identical to the source type - you are simply embedding that original type in your new plugin hierachy. Using the Embedded style of extension implicitly adds an "optional dependency" on the source plugin.

Injection

A plugin root level resource type (that is, a direct child of <plugin>) can define the parent resource types that it can run inside of. In effect, this injects the root level resource type as a child type to another plugin's resource type.

You define this directly under the root level type via the <runs-inside> element:

<runs-inside>
   <parent-resource-type name="JMX Server" plugin="JMX" />
   <parent-resource-type name="JBoss Server" plugin="JBossAS" />
</runs-inside>

Using the Injection style of extension implicitly adds an "optional dependency" on the parent plugin.

Optional Dependency Semantics

When using Embedded or Injection, you are essentially defining an "optional dependency". This means the plugin will still deploy, even if one of the plugins whose types it is embedding or injecting is missing. For example, the Hibernate plugin has an optional <runs-inside> dependency on the JBossAS plugin. If the JBossAS plugin is not deployed, the Hibernate plugin can still deploy, it just will not have any JBossAS related types in its type hierachy.

If any type relies on an optional plugin via the Embedded model (sourcePlugin attribute) and that optional plugin is missing, then the type will be ignored and will not exist.

If any type relies on optional plugins via the Injection model (runs-inside element) and some of those optional plugins are missing, then the type will exist, but it will not have parent resource types for those parent resource types whose plugins are missing.

Caveats

• Embedded: A <server> or <service> with a sourcePlugin/sourceType will take that source definition and duplicate it. This includes all children resources as well. The <server>/<service> can override things like discovery and class but today cannot add/remove/change any other metadata - the source type is copied as-is.

  For the Future?

  Do we want it also to add or remove things like configuration, operation and metric metadata? How do you denote that you want to remove one?

• Injection: Only a root level <server> or <service> can have a <runs-inside> element.

  For the Future?

  Do we also want to allow non-root-level types to accept <runs-inside>?

Discovery Classloaders

Each discovery component is assigned a "discovery classloader". If the discovery component's parent resource is the root platform, the discovery classloader is simply just the plugin classloader. If the parent resource is a top level server or of a low-level resource, the discovery classloader will be the plugin classloader but will have a parent classloader that is the classloader of the parent resource in order for the discovery component to talk to its parent resource using connection classes provided by the parent resource classloader.

Plugin developers can add things to their discovery component's classloader by implementing the ClassLoaderFacet - see the javadocs for that class for more information.

JBossAS extends the JMX plugin

The JMX plugin is a generic plugin and can be used by many other plugins. If you have a product that is manageable by JMX, you probably will want to add a dependency on the JMX plugin to pick up all its utilities. Note that the JMX plugin includes the third-party EMS library which provides generic JMX access to many different JMX vendors and implementations - any plugin that depends on the JMX plugin will also pick up the ability to use the EMS library for free.

In this example, consider that a JBossAS has a JMX server running inside of it that houses all the JBossAS 4.x services used for manageability.

JMX Plugin Descriptor:

<plugin name="JMX">
   <server name="JMX Server" discovery="JMXDiscoveryComponent" class="JMXServerComponent">
   ...
   </server>
</plugin>

JBossAS Plugin Descriptor:

<plugin name="JBossAS">
   <depends plugin="JMX" useClasses="true"/>
   <!-- JBossASXXXComponent classes extend the JMXXXXComponent classes -->
   <server name="JBossAS Server" discovery="JBossASDiscoveryComponent" class="JBossASServerComponent">
   ...
   </server>
</plugin>

Things to consider:

• The JBossAS plugin classloader will also have the JMX plugin's classes in it (due to useClasses="true" in the JBossAS plugin's <depends> tag).

• Note that the JBossAS plugin descriptor above does not actually define or use any source types related to or referencing the JMX plugin. But next we'll see how we can embed the JMX plugin's generic JVM MBeanServer into the JBossAS server resource type hierarchy.

Standalone JVM MBeanServer and Embedded In JBossAS

Recall that, since Java5, Java Virtual Machines have a "built-in" JMX MBeanServer called the "platform MBeanServer". Any JVM of version 5 or higher has this platform MBeanServer, allowing those JVMs to be monitored (the platform MBeanServer has MBeans to monitor things like the memory subsystem, the garbage collectors, the threading subsystem, et. al.). The JMX plugin can define resource types for each platform MBean, allowing it to monitor those MBeans as RHQ service resources.

The platform MBeanServer can be found in any standalone JVM process or it can be housed inside of a JBossAS server (that is, embedded inside the JBossAS VM process). We will use the Embedded extension model to define both of these situations:

JMX Plugin Descriptor:

<plugin name="JMX">
   <server name="JMX Server" discovery="JMXDiscoveryComponent" class="JMXServerComponent">
      <service name="VM Memory System"
               discovery="MBeanResourceDiscoveryComponent"
               class="MBeanResourceComponent"
               description="The memory system of the Java virtual machine">
      ...
      </service>
      <!-- other platform MBean services similar to above can be defined here -->
   ...
   </server>
</plugin>

JBossAS Plugin Descriptor:

<plugin name="JBossAS">
   <depends plugin="JMX" useClasses="true"/>
   <!-- JBossASXXXComponent classes extend the JMXXXXComponent classes -->
   <server name="JBossAS Server" discovery="JBossASDiscoveryComponent" class="JBossASServerComponent">
      <!-- effectively duplicates the JMX plugin's resource type and its children types -->
      <server name="JBoss AS JVM"
              description="JVM of the JBossAS"
              sourcePlugin="JMX"
              sourceType="JMX Server"
              discovery="org.rhq.plugins.jmx.EmbeddedJMXServerDiscoveryComponent"
              class="org.rhq.plugins.jmx.JMXServerComponent">
      ...
      </server>
   ...
   </server>
</plugin>

Things to consider:

• <server> has sourcePlugin and sourceType - this typically indicates an "optional" dependency. However, because the JBossAS plugin needs to use and extend the JMX plugin's component classes, it specifies <depends plugin="JMX" useClasses="true"/> changing it to a "requires" dependency - therefore, you cannot deploy the JBossAS plugin without also deploying the JMX plugin with it.

• We now have two JMX Server discoveries happening, one with JMXDiscoveryComponent (from the JMX plugin) and one with org.rhq.plugins.jmx.EmbeddedJMXServerDiscoveryComponent. This means the JBossAS plugin is asking for a special discovery component to run to discover this "JBoss AS JVM" resource. This illustrates that an embedded resource type can be discovered using a different discovery component from that of the source plugin type.

• The sourcePlugin/sourceType makes a duplicate copy of a resource type and gives it a unique name. During runtime, they are seen as two distinct and different resource types.

Hibernate Able to Run in Either Standalone JVM or JBossAS

Hibernate can be deployed/run in either a standalone J2SE JVM instance or a JBossAS server. We will use the Injection extension model to define this situation:

JMX Plugin Descriptor:

<plugin name="JMX">
   <server name="JMX Server" discovery="JMXDiscoveryComponent" class="JMXServerComponent">
   ...
   </server>
</plugin>

JBossAS Plugin Descriptor:

<plugin name="JBossAS">
   <depends plugin="JMX" useClasses="true"/>
   <!-- JBossASXXXComponent classes extend the JMXXXXComponent classes -->
   <server name="JBossAS Server" discovery="JBossASDiscoveryComponent" class="JBossASServerComponent">
   ...
   </server>
</plugin>

Hibernate Plugin Descriptor:

   <depends plugin="JMX" useClasses="true"/>
   <service name="Hibernate Statistics"
            discovery="org.rhq.plugins.jmx.MBeanResourceDiscoveryComponent" class="StatisticsComponent">
      <runs-inside>
         <parent-resource-type name="JMX Server" plugin="JMX"/>
         <parent-resource-type name="JBossAS Server" plugin="JBossAS"/>
      </runs-inside>
   ...
   </service>
</plugin>

Things to consider:

• Plugins can have "multiple dependency" support - a plugin can depend on more than one other plugin. If Hibernate can run inside a Tomcat Server, we could have added a <parent-resource-type> element to describe this. This would add a second optional dependency on the Tomcat plugin. Remember, however, that a plugin descriptor can only have one dependency that denotes "useClasses=true". Because the Hibernate plugin uses and extends the JMX plugin classes, it needs to <depend> on the JMX plugin with useClasses=true.

• Hibernate is injecting its "Hibernate Statistics" resource type definition as a child to the parent types of JMX Server and JBossAS Server.

• Because the Hibernate plugin has a direct dependency on the JBossAS plugin, it also implicitly is a dependent of any other plugins the JBossAS plugin is dependent on. It just so happens in this example, there are no additional dependencies, but the point should be noted that transitive dependencies like that are supported.